package com.weed.core;

/**
 * 函数说明：
 *    缓存接口，便于实现二级缓存。
 *
 * @author Jason Zhuo
 * @version 1.0
 */

import java.util.Map;

/**
 *  实现缓存算法，要求所有的算法必须具有线程安全。
 */
public interface Cache {
  /**
   * 获得缓存项目。
   * @param key 唯一键
   * @return 缓存对象
   * @throws WeedException
   */
  public Object read(Object key) throws WeedException;

  /**
   * 从缓存中获得项目，与Read用法一至。
   * @param key 唯一键
   * @return 缓存对象
   * @throws WeedException
   */
  public Object get(Object key) throws WeedException;

  /**
   * 添加一个项目到缓存中。
   * @param key 唯一键
   * @param value 对象
   * @throws WeedException
   */
  public void put(Object key, Object value) throws WeedException;

  /**
   * 更新缓存中的对象，如果不存在就更新。
   * @param key  唯一键
   * @param value 对象
   * @throws WeedException
   */
  public void update(Object key, Object value) throws WeedException;

  /**
   * 从缓存中移除一项，根据指定的键值。
   */
  public void remove(Object key) throws WeedException;

  /**
   * 清除缓存。
   */
  public void clear() throws WeedException;

  /**
   * 清除所有对象。
   */
  public void destroy() throws WeedException;

  /**
   * 如果这是一个群集对象，将被锁定，不能被清除.
   */
  public void lock(Object key) throws WeedException;

  /**
   * 对锁定的项目进行解锁。
   */
  public void unlock(Object key) throws WeedException;

  /**
   * 产生一个标识，记录对象产生的标识。
   */
  public long nextTimestamp();

  /**
   * 获得缓存产生的时间。
   */
  public int getTimeout();

  /**
   * 获得缓存的名称。
   */
  public String getRegionName();

  /**
   * 获得这个缓存在内存中消耗的大小。
   *
   * @return 如果返回-1为不支持该方法。
   */
  public long getSizeInMemory();

  /**
   * 获得在内存中的对象总数。
   *
   * @return 如果返回-1为不支持该方法。
   */
  public long getElementCountInMemory();

  /**
   * 获得缓存到磁盘的对象总数。
   *
   * @return 如果返回-1为不支持该方法。
   */
  public long getElementCountOnDisk();

  /**
   * 操作选项。
   */
  public Map toMap();
}

